home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / mac / developm / source / drgnsmth.cpt / Dragonsmith 1.1 / Documentation / Dragonsmith Manual (text) < prev    next >
Encoding:
Text File  |  1992-10-11  |  82.0 KB  |  2,311 lines
  1. ------------------------------------------------------
  2. Dragonsmith Programmer╒s Manual (text format)
  3. ------------------------------------------------------
  4.  
  5.  
  6. version 1.1
  7. Sunday, October 11, 1992
  8. by Paul Hoffman
  9.  
  10. ╥Dragons do not enter into this story╔╙
  11.  
  12.  
  13. Send bug reports, comments, and suggestions to:
  14.  
  15. Mail        Paul Hoffman
  16.             840 S. First, Apt.1
  17.             Ann Arbor MI 48103
  18.             U.S.A.
  19.     
  20. Internet    paul.hoffman@um.cc.umich.edu
  21.  
  22. AFS            /afs/umich.edu/user/n/k/nkuitse
  23.  
  24.  
  25.     **************************************************
  26.     * NOTE:                                          *
  27.     *                                                *
  28.     *    This document is a text-only version of the  *
  29.     *    file ╥Dragonsmith Programmer╒s Manual╙       *
  30.     *                                                *
  31.     *    The text is all the same, but a few tables   *
  32.     *    and figures are missing from this file       *
  33.     *                                                *
  34.     **************************************************
  35.  
  36. ------------------------------------------------------
  37. CONTENTS
  38. ------------------------------------------------------
  39.  
  40. Introduction
  41.     What is Dragonsmith?
  42.     What is drag-and-drop, and what is it good for?
  43.     How does the Finder know what can be drag-and-dropped where?
  44.     What is a dragon, and why is it called that?
  45.     What can Dragonsmith do, and what can╒t it do?
  46.     Can I use Dragonsmith with System 6?
  47.     Why use object-oriented programming (OOP)?
  48.     Where can I find out more about OOP?
  49.     Does Dragonsmith use the THINK╩Class Library?
  50.     How do I create my own dragon?
  51.     How do I upgrade from Dragonsmith v1.0b2 to v1.1?
  52.     Will I have to rewrite my code when the next release of Dragonsmith comes out?
  53.  
  54. Getting started
  55.     Dragonsmith 1.1 files
  56.     Upgrading from Dragonsmith 1.0b2
  57.     PreDragon
  58.     Creating the project file
  59.     Creating the project resource file
  60.     Writing a subclass of Dragon
  61.     Compiling and debugging your dragon
  62.  
  63. Program flow
  64.  
  65. When something goes wrong╔
  66.     Error ╘Can╒t open file ╥PreDragon╙╒
  67.     Syntax error at the first line
  68.     Link error ╘Undefined:╩CreateGDragon╒
  69.     AEProcessAppleEvent returns error ╨608 (noOutstandingHLE)
  70.     AEProcessAppleEvent returns error ╨609 (connectionInvalid)
  71.     Your dragon won╒t drop (or it ╘overdrops╒)
  72.     Your dragon crashes shortly after an Apple event is handled
  73.  
  74. Notes on Apple events
  75.  
  76. How to╔
  77.     Automatic disk and folder opening
  78.     Adding a menu
  79.     Adding a preference setting
  80.  
  81. Dragons ahoy!
  82.  
  83. Dragon instance variables
  84.  
  85. Dragon methods
  86.  
  87. Resources
  88.  
  89.  
  90. ------------------------------------------------------
  91. INTRODUCTION
  92. ------------------------------------------------------
  93.  
  94. What is Dragonsmith?
  95.  
  96. Dragonsmith is an object-oriented framework for developing drag-and-drop
  97. applications under Macintosh System╩7. 
  98.  
  99. What is drag-and-drop, and what is it good for?
  100.  
  101. The drag-and-drop feature of the System 7 Finder lets you open files using
  102. an application other than the one that created it.  Here╒s a (rather
  103. simplistic) outline of how this works:
  104.     Ñ The user drags a file╒s icon onto that of a drag-and-drop application
  105.     Ñ The Finder launches the application (if it wasn╒t already running)
  106.     Ñ The Finder sends the application an Apple event telling it to open the
  107. file
  108.     Ñ The application opens the file
  109.  
  110. How does the Finder know what can be drag-and-dropped where?
  111.  
  112. As you drag a file╒s icon around the desktop, the Finder hilites an
  113. application icon the pointer passes over only if the application is capable
  114. of opening that type of file.  (The situation is more complicated when you
  115. drag more than one icon at a time.)  The Finder uses the desktop database to
  116. decide which applications can open which types of files; this information in
  117. turn comes from ╘FREF╒ resources found in the application files.  Because
  118. the desktop database sometimes gets messed up (and out of a general sense of
  119. caution), applications developed with Dragonsmith do their own checking of
  120. ╘FREF╒ resources and file types.
  121.  
  122. What is a dragon, and why is it called that?
  123.  
  124. A dragon is an application that is driven primarily by drag-and-drop ╤ it
  125. doesn╒t do much if you double-click on its icon, but drop a few files on it
  126. and watch it go!  Instead of ╘opening╒ drag-and-dropped files, dragons
  127. ╘process╒ them.  This ╘processing╒ can be any type of action ╤ deleting a
  128. file, compiling an index of it, extracting sounds from its resource fork,
  129. etc.  Here╒s a list of some dragon-and-drop applications and what they do:
  130.  
  131.     Alias Director 2.7    Creates aliases to files, folders, and disks.
  132.     Alias Finder        Opens the Finder window containing the original file or
  133.                             folder of an alias.
  134.     FileTyper 3.0        Allows one to change the file type, creator, and other
  135.                             attributes of files.
  136.     GroupInfo            Displays the total amount of disk space used by a group
  137.                             of files and folders.
  138.     Paradigma 2.0        Finds and replaces strings in a text file.
  139.     Save a BNDL            Refreshes a file╒s BNDL information to update its icons,
  140.                             etc. in the Finder.
  141.     StuffIt Expander¬    Expands StuffIt and CompactPro archives and AppleLink
  142.                             packages.
  143.     Text Merger 1.02    Merges several text files into a single file.
  144.  
  145. There is a great deal of variety among these applications (and others like
  146. them).  Some of them will accept drag-and-dropped folders or disks in
  147. addition to files.  Some process files quietly and quit automatically when
  148. they╒re done; others stick around to give you the opportunity to change
  149. settings.  Some only run in System 7; others will run in System 6, using the
  150. Standard File routines to choose the files you want to process.  The
  151. important thing is what they all have in common ╤ drag-and-drop ╘batch╒
  152. processing of files.
  153.  
  154. Why the name dragon?
  155.  
  156.     Ñ Dragons are drag-and-dropped on (of course).
  157.     Ñ Dragons are distant cousins of UNIX daemons (which, strangely enough, do
  158. their thing in the wings).
  159.     Ñ Dragons have been known to enter (quite uninvited) into the stories of a
  160. certain amateur writer.
  161.  
  162. What can Dragonsmith do, and what can╒t it do?
  163.  
  164. Dragonsmith can be used to create any application, but it wouldn╒t make
  165. sense to develop one that didn╒t feature drag-and-drop prominently.  There
  166. wouldn╒t be much point, for example, in using Dragonsmith to make a word
  167. processor ╤ it would be more suited for an application that displays the
  168. total number of words and paragraphs in a group of text files dropped on it.
  169.  
  170. Because most dragons will probably perform simple tasks, Dragonsmith has
  171. been designed with simplicity in mind.  A simple Dragonsmith-produced
  172. application typically requires only about 20╨25K of disk space and runs in
  173. 40╨50K of memory.  Because of the object-oriented nature of the Dragonsmith
  174. kit, however, advanced features can easily be added to a dragon.
  175.  
  176. On the other hand, dragons developed with Dragonsmith have several more or
  177. less advanced capabilities:
  178.  
  179. Preferences
  180. Automatic resource-based preferences file management is built
  181. into all dragons.  Any dragon that you create can store, alter, and retrieve
  182. any number of preferences.  The user can ask a dragon to use any particular
  183. preferences file that belongs to it by double-clicking on that file in the
  184. Finder.  As long as you╒re careful to program defensively, the dragon will
  185. still run normally if a preferences file could not be found or created.
  186.  
  187. Folder searching
  188. You can specify that folders and disks will automatically
  189. be opened recursively to any desired depth in search of files to be
  190. processed.
  191.  
  192. Alias resolution
  193. If folder searching is enabled, then any alias files
  194. encountered may (optionally) be automatically resolved.
  195.  
  196. Safe file handling
  197. A dragon will ╥see╙ only those documents (files, folders,
  198. and volumes) that the Finder would allow the user to drag-and-drop on it. 
  199. If the dragon looks inside a folder dropped on it, or if it receives an Open
  200. Documents event from a source other than the Finder, it will ignore any
  201. files it doesn╒t know what to do with.
  202.  
  203. Smart file filtering
  204. A dragon can easily be made to process only files that
  205. match specific criteria besides just the file type ╤ name, size, creator,
  206. location, etc.
  207.  
  208. Background processing
  209. A dragon will run quietly in the background if the
  210. user decides to switch to (or launch) another application after dropping
  211. files on it; the dragon will take as much or as little CPU time away from
  212. other applications as you want it to.
  213.  
  214. Apple event queuing
  215. The user can drag-and-drop documents on a dragon (or
  216. another Apple-event-savvy application can send the dragon an Open Documents
  217. event) while the dragon is busy at work on something else ╤ each batch of
  218. documents will be processed in the order in which it was received.
  219.  
  220. Auto-quit
  221. You can specify that a dragon will automatically quit after
  222. processing drag-and-dropped documents (or if double-clicked in the Finder).
  223.  
  224. Environment checking
  225. A dragon will terminate gracefully if launched in a
  226. run-time environment insufficient for its needs ╤ and the specifications for
  227. its run-time requirements can be changed without any source code
  228. modifications.
  229.  
  230.  
  231. The following features are not supported by Dragonsmith 1.1 but are under
  232. consideration for future releases:
  233.  
  234. Apple Event objects
  235. Adding Apple Event Object Model and scripting support is
  236. a high priority.  This will enable control of dragons by Apple event-savvy
  237. applications, including scripting environments like UserLand Frontier and
  238. the forthcoming AppleScript.  A small Dragon suite of custom Apple events is
  239. a possibility.
  240.  
  241. Improved error handing
  242. The Dragon class╒s error handling capability is
  243. currently rudimentary.  Improvements will include better reporting of errors
  244. to the user and, when Apple Event Object support is added, to client
  245. applications.
  246.  
  247. Progress window
  248. Also in the works is a movable modal dialog to show what
  249. documents are being processed, display error messages, etc.
  250.  
  251. More sophisticated preferences handling
  252. There is currently no support in the Dragon and Preferences classes for
  253. preferences file ╘Open,╒ ╘Save╒ and ╘Save As╔╒ operations.  These
  254. capabilities should form part of a general preferences-editing interface ╤
  255. perhaps via a ╘Preferences╔╒ item added to the ╘Edit╒ menu.
  256.  
  257. Drakelings
  258. There is a growing trend in the Macintosh world toward
  259. ╘miniature╒ custom stand-alone drag-and-drop applications created by a
  260. ╘master╒ application ╤ Frontier╒s applets belong to this category, as do the
  261. ╘ParaDoids╒ created by Espen Aarseth╒s excellent Paradigma, and the
  262. ╘AutoTypers╒ in Daniel Azuma╒s FileTyper package.  Implementing this type of
  263. document-application hybrid in Dragonsmith is a high priority.
  264.  
  265. Faceless dragons
  266. Some dragons don╒t need any user interface.  The Dragon
  267. class currently uses an instance variable autoQuit to designate that a
  268. dragon will quit immediately after receiving the first Open Documents event
  269. it receives.  A better solution, however, would be a simpler class (of which
  270. Dragon would become a subclass) designed for creating background-only
  271. dragons.  This could significantly reduce the size of simple faceless
  272. dragons, which is especially important in light of the interface
  273. enhancements planned for the Dragon class.
  274.  
  275. FilterTop support
  276. The freeware FilterTop project currently under development
  277. will provide a programming framework similar in some ways to that of
  278. Dragonsmith. FilterTop is likely to garner a good deal of popularity, and
  279. Dragonsmith and it should be able to complement each other very nicely.
  280.  
  281. Can I use Dragonsmith with System 6?
  282.  
  283. No, System 7 is required.  The whole point of dragons is defeated in a
  284. no-drag-and-drop, no-Apple-events environment.
  285.  
  286. Why use object-oriented programming (OOP)?
  287.  
  288. The center of Dragonsmith╒s drag-and-drop framework is provided the Dragon
  289. class.  To write your own dragon, you╒ll create a new subclass of Dragon
  290. that ╘inherits╒ the bulk of its code.  Using OOP, you can easily override or
  291. extend Dragon╒s behavior without altering any source files ╤ you can change
  292. as much or as little as you need to.
  293.  
  294. Where can I find out more about OOP?
  295.  
  296. You might begin by reading parts of the THINK╩C Object-Oriented Programming
  297. Manual (for THINK╩C╩5.0).  Pages 19╨24 and 28╨51 are a good starting point,
  298. and pages 81╨86 contain some information specific to using OOP in THINK╩C.
  299.  
  300. Does Dragonsmith use the THINK╩Class Library?
  301.  
  302. No.  For most drag-and-drop applications, the TCL is overkill ╤ it contains
  303. a vast amount of code that most dragons will never need.
  304.  
  305. On the other hand, you could use the TCL ╤ using code from Dragon.c, write a
  306. subclass of CApplication called CDragonApp or some such.  It shouldn╒t be
  307. overwhelmingly difficult.
  308.  
  309. [Remember, the source code in Dragonsmith may be freely altered and used for
  310. any purpose, subject only to the restrictions mentioned at the beginning of
  311. each file.  Applications developed using Dragonsmith may be sold or given
  312. away without restriction.]
  313.  
  314. How do I create my own dragon?
  315.  
  316. The easiest way is to base your dragon on one of the template classes
  317. provided.  Each of these files has step-by-step instructions on how to use
  318. it to write your own dragon:
  319.  
  320.     PlainTmpl.c        A very simple ╘auto-quit╒ dragon without any interface
  321.     MenusTmpl.c        A simple dragon with an added menu
  322.     PrefsTmpl.c        A simple dragon with an added menu and preferences settings
  323.  
  324. You might also want to read the source code files for the finished dragons
  325. provided with this release of Dragonsmith ╤ DFileCleaver.c, DFilePaths.c,
  326. and DPasser.c
  327.  
  328. How do I upgrade from Dragonsmith v1.0b2 to v1.1?
  329.  
  330. Follow the instructions in the Getting Started section below.  The basic
  331. steps are:
  332.  
  333.     Ñ Replace the old Dragonsmith.╣ with the one in this release.  You can
  334. throw away Dragonsmith.debug.╣ ╤ it╒s no longer needed.
  335.  
  336.     Ñ Move the bulk of your ProcessDroppings method to ProcessFile (and
  337. possibly move some to the BeginProcessing and EndProcessing methods) ╤ this
  338. may require adding a few instance variables.  Your dragon will no longer
  339. need to directly access the data in the Open Documents event.
  340.  
  341.     Ñ If your dragon added any menus, rewrite its SetUpMenus and DoMenu methods
  342. and remove its basic Apple, File, and Edit menu functionality ╤ they╒re now
  343. implemented in Dragon.
  344.  
  345.     Ñ Change your dragon╒s signature from ╘Drgn╒ to some other unique value, if
  346. you hadn╒t already.
  347.  
  348.     Ñ Add some resources to your project╒s resource file.
  349.  
  350.     Ñ Recompile all the files in your project.
  351.  
  352. Will I have to rewrite my code when the next release of Dragonsmith comes
  353. out?
  354.  
  355. Hopefully not.  This manual will warn you about certain features of the
  356. Dragon class that, for future compatibility, are best left alone.  Still,
  357. the most important thing is to get the most out of the functionality already
  358. in the Dragon class ╤ future incompatibility dangers shouldn╒t inhibit you
  359. more than a little.
  360.  
  361.  
  362. ------------------------------------------------------
  363. GETTING STARTED
  364. ------------------------------------------------------
  365.  
  366. Dragonsmith 1.1 files
  367.  
  368. Dragonsmith
  369.     ! Read me
  370.     Base files  <Normally, you shouldn╒t add to this folder or alter the files
  371.             in it ╤ if you use a copy of one of these files, move it up into
  372.             the Dragonsmith folder>
  373.         Classes
  374.             AppleEventQueue.c
  375.             AppleEventQueue.h
  376.             Preferences.c  <A resource-based preferences management class that
  377.                 may be used outside of Dragonsmith>
  378.             Preferences.h
  379.         DFileCleaver.c
  380.         DFilePaths.c
  381.         DPasser.c
  382.         Dragon.c  <Code for the Dragon class>
  383.         Dragon.h
  384.         Dragonsmith TMPLs  <ResEdit templates for editing custom resource types used
  385. in Dragonsmith>
  386.         Dragonsmith.╣    <Use a copy of this project file with your code added for
  387. greater debugging control than is provided by (a copy of) Template.╣>
  388.         FileCleaver.╣
  389.         FileCleaver.╣.rsrc
  390.         FilePaths.╣
  391.         FilePaths.╣.rsrc
  392.         Main.c  <Contains the function main used for all dragons>
  393.         Passer.╣
  394.         Passer.╣.rsrc
  395.         PreDragon.c  <Source for the PreDragon precompiled headers file used by
  396. Dragonsmith projects>
  397.         Utilities  <Source code containing various utility functions>
  398.             [numerous files]
  399.     Documentation
  400.         ! Release notes
  401.         Dragonsmith Programmer╒s Manual
  402.         Dragonsmith Manual (text)  <This file>
  403.         Preferences class notes
  404.     Dragons
  405.         ! Read Me (Dragons)
  406.         File Cleaver 1.1
  407.         File Paths 1.1  <Used to produce this list of files>
  408.         Passer 1.1  <A dragon that passes Open Documents events to high level
  409. event-aware processes ╤ vital for debugging Apple event-handling code in the
  410. THINK╩C Debugger>
  411.     Template files  <Source code and resource template files for three simple
  412. kinds of Dragon subclass>
  413.         DMenusTmpl.c
  414.         DPlainTmpl.c
  415.         DPrefsTmpl.c
  416.         MenusTmpl.╣.rsrc
  417.         PlainTmpl.╣.rsrc
  418.         PrefsTmpl.╣.rsrc
  419.     Template.╣  <Project file to copy and use with the template files>
  420.  
  421. Upgrading from Dragonsmith 1.0b2
  422.  
  423. The original release of Dragonsmith was much more simplistic.  Processing of
  424. documents was treated as a single step ╤ the dragon developer was required
  425. to write (in ProcessDroppings) a loop to extract, then process, each
  426. document from the Open Documents Event.  Any desired filtering of documents
  427. (treating files and folders differently, resolving alias files, opening only
  428. files of a certain type, etc.) had to be done by the subclass of Dragon. 
  429. Programmers who needed file information were responsible for calling
  430. PBGetCatInfo themselves.  In Dragonsmith 1.1, most of this ╘grunt╒ work is
  431. done for you by the Dragon class.
  432.  
  433. The changes in functionality have brought about several significant changes
  434. in the Dragon class iinterface, and all Dragon 1.0b2 subclasses will have to
  435. be modified to work with Dragon 1.1.
  436.  
  437. ProcessDroppings
  438.  
  439. In Dragonsmith 1.0b2, every Dragon subclass had to override
  440. ProcessDroppings.  In version 1.1, that╒s no longer true.  In general,
  441. ProcessFile (and possibly ProcessDirectory) should be overridden;
  442. ProcessDroppings should not.
  443.  
  444. To update your dragon to Dragonsmith 1.1, you╒ll probably move most of the
  445. code from your ProcessDroppings method to ProcessFile ╤ though some of it
  446. may need to go into BeginProcessing and EndProcessing.  Updating your dragon
  447. will probably also require changing a few local variables in your old
  448. ProcessDroppings method to instance variables.
  449.  
  450. In addition, ProcessDroppings╒ parameters have changed.  The docs parameter
  451. isn╒t needed any more because information about the current file or
  452. directory is always accessible in *curDocFSS (an FSSpec record) and
  453. *curDocPB (a multi-purpose parameter block subsuming the HParamBlockRec,
  454. CInfoPBRec, and other low-level File Manager param-blocks).  The numDocs
  455. parameter has no counterpart in Dragon 1.1 ╤ a more sophisticated file
  456. counting and tracking mechanism is planned for a future version of
  457. Dragonsmith.
  458.  
  459. Menus
  460.  
  461. The new Dragon class implements standard Apple and Edit menus, plus a File
  462. menu with a single Quit item.  The DFilePaths class released as part of
  463. Dragonsmith 1.0b2 used a different means to implement essentially the same
  464. menus ╤ any dragons modeled after it will need to be changed to adhere to
  465. Dragon 1.1╒s menu scheme.  Look at the DMenusTmpl.c file for an example of
  466. how a dragon should add menus.
  467.  
  468. Signatures and the Desktop Manager
  469.  
  470. Dragonsmith 1.0b2 didn╒t make it clear that every new dragon should have a
  471. unique application signature (and, for clarity, a distinct icon in the
  472. Finder).  If more than one application in your Mac work environment has the
  473. same signature, then drag-and-drop for either of them (or both) may not work
  474. properly.  You are encouraged to assign your dragons unique signatures and
  475. register each one with Apple.
  476.  
  477. PreDragon
  478.  
  479. One of the first things you should do is to make a precompiled headers file
  480. from PreDragon.c.  The resulting file should be named PreDragon and placed
  481. in the Base Files folder.  The source files in the Dragonsmith kit all rely
  482. on these precompiled headers.
  483.  
  484. Creating the project file
  485.  
  486. Start with a copy of Template.╣ (or a copy of Dragonsmith.╣ if you want more
  487. control over debugging), then add the file which holds the source code for
  488. your dragon.  The code for a simple dragon will most likely fit into a
  489. single segment, not counting extra segments (such as ╘CODE╒ 0) that THINK╩C
  490. creates transparently.
  491.  
  492. Make sure you choose ╘Set Project Type╔╒ from THINK╩C╒s Project menus and
  493. set the appropriate values for Creator (signature), partition, and SIZE
  494. flags.
  495.  
  496. Creating the project resource file
  497.  
  498. In general, you should start with a copy of one of the ╔Tmpl.╣.rsrc files
  499. and make modifications as necessary.  The first changes you make should be
  500. in ╘STR╩╒ 128, the ╘FREF╒ resources, and ╘DrPr╒ 128.  The Resources section
  501. in this document and the source files in the ╘Template Files╒ folder contain
  502. descriptions of the various resources used by Dragonsmith, as well as
  503. information on which resources to change and how.
  504.  
  505. Writing a subclass of Dragon
  506.  
  507. It╒s recommended that you start with one of the template classes provided in
  508. the ╘Template Files╒ folder.  Information on how to make a dragon this way
  509. is provided in the source files.  If you had previously developed a dragon
  510. using Dragonsmith 1.0b2, you should read the section Upgrading from
  511. Dragonsmith 1.0b2 above.  For tips on adding specific functionality to your
  512. dragon, refer to the section How To╔ below.
  513.  
  514. Constructor method
  515.  
  516. Your dragon should use a constructor (a method with no return-value, whose
  517. name is that of the class to which it belongs) to initialize any instance
  518. variables it adds.  Your dragon╒s constructor will be executed (immediately
  519. after the Dragon class╒s constructor) when the gDragon object is made in
  520. CreateGDragon.  It should set any default instance variable values that you
  521. want to be different from the values assigned in Dragon::Dragon.  If your
  522. dragon implements any custom preferences resources, you should add instance
  523. variables to hold their values and your constructor should set defaults for
  524. them (in case the ReadPrefs method fails).
  525.  
  526. ProcessFile and ProcessDirectory
  527.  
  528. These are the two most important methods ╤ without overriding one or both of
  529. them, your dragon won╒t do anything.  If your dragon makes simple changes to
  530. a file or directory╒s catalog information, it can use the macros described
  531. below (curFileType, curDocCreated, etc.) to change the appropriate fields in
  532. curDocPB, then (at the end of ProcessFile or ProcessDirectory) call the
  533. SaveDocInfo method to have the information changed on disk.  For more
  534. information, see Macros below and read the notes for SaveDocInfo in the
  535. Methods section.
  536.  
  537. CreateGDragon
  538.  
  539. This function is not defined in Dragon.c ╤ the code for it must be found in
  540. one of your dragon╒s source files.  It performs the very important task of
  541. creating a dragon object of the desired Dragon subclass, and can be written
  542. as simply as this:
  543.  
  544. Dragon *CreateGDragon (void)
  545. {
  546.     return (Dragon *) new DMyDragonClass;
  547. }
  548.  
  549. Compiling and debugging your dragon
  550.  
  551. Passer
  552.  
  553. Drag-and-drop is at the heart of dragons, so you╒ll need a way to debug your
  554. dragon╒s ProcessFile method (and related code).  Unfortunately, there╒s no
  555. way to drag-and-drop files onto your dragon while it╒s running in the
  556. THINK╩C Debugger.  Instead, you╒ll have to use the ╘Passer╒ dragon provided
  557. with Dragonsmith 1.1 to transmit Open Documents events to your dragon while
  558. it╒s being debugged.  To do so, choose ╘Run╒ from the Project menu in
  559. THINK╩C, then start up Passer and choose ╘Target╔╒ from its Options menu. 
  560. Once you╒ve selected your dragon╒s process from the resulting PPCBrowser
  561. dialog, any Open Documents events sent to Passer will simply be rerouted to
  562. your dragon without modification.  Set a breakpoint in ProcessFile (or
  563. ProcessDirectory) to ╘catch╒ the event, then debug from there.
  564.  
  565. Apple events and the THINK╩C Debugger
  566.  
  567. While running your dragon in the THINK╩C Debugger, you must be careful not
  568. to set any breakpoints in code executed between a call to WaitNextEvent that
  569. returns a high-level event and the call to AEProcessAppleEvent that
  570. dispatches the event to the appropriate Apple event handler.  You can set
  571. breakpoints in the handler itself and in the Dragon method it calls.  If you
  572. forget this and set a breakpoint in the wrong place, AEProcessAppleEvent
  573. will return a noOutstandingHLE (╨608) error and the event will not be
  574. dispatched.  Presumably this is due to a time-out internal to the Apple
  575. Event Maneger package (╘PACK╒ 8), because it seems to happen whether the
  576. source of the event specifies a time-out value or not.
  577.  
  578. If you want to send yourself an Apple event, use the kCurrentProcess
  579. constant instead of sending by signature ╤ your signature under the THINK╩C
  580. Debugger is ╘KAHL╒ and THINK╩C or the THINK╩C Debugger may intercept the
  581. event.
  582.  
  583. Don╒t set any breakpoints between a call to WaitNextEvent that returns a
  584. high-level event and the ensuing call to AEProcessAppleEvent.  Otherwise,
  585. the Apple event will time out and AEProcessAppleEvent will return ╨608
  586. (noOutstandingHLE).  This may also be true of AcceptHighLevelEvent ╤ it
  587. hasn╒t been tested.
  588.  
  589.  
  590.  
  591. ------------------------------------------------------
  592. PROGRAM FLOW
  593. ------------------------------------------------------
  594.  
  595. Figure 1 shows the flow of execution of a dragon as it starts up and
  596. subsequently receives an Open Documents event:
  597.  
  598.     <Figure 1 omitted>
  599.  
  600. The main event loop in Dragon is essentially the same as that in almost any
  601. Macintosh application.  For each event returned by WaitNextEvent, the
  602. DoEvent method calls the appropriate event-handling method ╤ DoMouseDown,
  603. DoSuspend, DoResume, DoKeyDown, etc.  When an Open Documents event is
  604. received by your dragon, DoEvent calls DoHighLevelEvent, which dispatches
  605. the event to HandleOdoc, the Open Documents handler installed in the
  606. InitAppleEvents method.  HandleOdoc in turn sends a DoOdoc message to
  607. gDragon, the global dragon object.  DoOdoc extracts the event╒s
  608. keyDirectObject parameter (the list of documents to open) and uses it as a
  609. parameter to ProcessDroppings, which calls ProcessDoc for each document in
  610. the list.
  611.  
  612. Things can get considerably more complicated than this diagram shows:
  613.  
  614.     Ñ When dirDepthLimit < 0 and ProcessDoc encounters a directory,
  615. ProcessDocsInDirectory will be executed instead of ProcessFile or
  616. ProcessDirectory, and recursion back to ProcessDoc will probably occur.
  617.  
  618.     Ñ The ProcessOwnedFile method will be called instead if your dragon is
  619. asked to open a file that belongs to it (i.e., one whose creator code is
  620. your dragon╒s signature).  Typically, this is a preferences file, but a
  621. Dragon subclass might use this feature for other things ╤ to implement
  622. script files, for example.
  623.  
  624.     Ñ If a document your dragon is asked to open is of a type that it doesn╒t
  625. ╘know about╒ (i.e., that is not covered by its ╘FREF╒ resources), or if the
  626. document is rejected by CustomFilterDoc, then ProcessDoc will not be
  627. executed.
  628.  
  629.     Ñ If the dragon is busy processing something when an Open Documents event
  630. is received, DoOdoc will call SuspendAEvent instead of ProcessDroppings. 
  631. This will add the event to a queue for later processing ╤ the event will be
  632. ╘on hold╒ until all preceding ╘odoc╒ events have been processed.  The next
  633. time WaitNextEvent fails to return an event, Run will call ResumeAEvent to
  634. complete handling of the event.  This way, all Open Documents events will be
  635. processed in the order in which they were received.  Note that when a Quit
  636. Application event is received, any suspended events will return an error to
  637. the sending process and will not result in any documents being processed.
  638.  
  639.  
  640. ------------------------------------------------------
  641. WHEN SOMETHING GOES WRONG╔
  642. ------------------------------------------------------
  643.  
  644. Error ╘Can╒t open file ╥PreDragon╙╒
  645.  
  646. Either you haven╒t created the PreDragon precompiled headers file from
  647. PreDragon.c, or it╒s located where THINK╩C can╒t find it.  See Creating your
  648. dragon skeleton above for more information.
  649.  
  650. Syntax error at the first line
  651.  
  652. The problem may be with your project prefix ╤ it should end with the line
  653.  
  654.     #include "PreDragon"
  655.  
  656. Choose ╘Options╔╒ from THINK╩C╒s Edit menu to bring up a dialog where you
  657. can set this.  You should not #include <MacHeaders> in the project prefix.
  658.  
  659. Link error ╘Undefined:╩CreateGDragon╒
  660.  
  661. You╒ve forgotten to define (write the code for) the CreateGDragon function. 
  662. It should create an instance of your Dragon subclass (not of Dragon) and
  663. return a reference to the object, like this:
  664.  
  665. Dragon *CreateGDragon (void)
  666. {
  667.     return (Dragon *) new DMyDragonClass;
  668. }
  669.  
  670. AEProcessAppleEvent returns error ╨608 (noOutstandingHLE)
  671.  
  672. You may have set a breakpoint between the WaitNextEvent call that obtained
  673. the event and the AEProcessAppleEvent call that dispatched to your handler ╤
  674. see Compiling and debugging your dragon above for more information on using
  675. the THINK╩C Debugger.
  676.  
  677. It is safe to set a breakpoint in your Apple event handler, or in the code
  678. that it calls (DoOapp, DoOdoc, DoPdoc, or DoQuit).
  679.  
  680. AEProcessAppleEvent returns error ╨609 (connectionInvalid)
  681.  
  682. You may have forgotten to set the ╘high level event aware╒ flag in your
  683. project╒s ╘SIZE╒ resource.  Both the sender and receiver of a high-level
  684. event must have this flag set.
  685.  
  686. Your dragon won╒t drop (or it ╘overdrops╒)
  687.  
  688. If this is the first time you╒ve built your dragon, check to make sure that
  689. you╒ve given it a unique signature and not ╘????╒ (or ╘Drgn╒ ╤ Dragonsmith
  690. v1.0b2 implied that you should use this value).
  691.  
  692. If you╒ve built it before, then there may be a problem with the desktop
  693. database.  Delete any obsolete versions of your dragon that accepted
  694. different types (or move them to a floppy disk) and rebuild the desktop. 
  695. (The utility application ╘Save a BNDL╒ may let you avoid this step ╤ but use
  696. it with caution.)
  697.  
  698. Your dragon crashes shortly after an Apple event is handled
  699.  
  700. Your Apple event may be returning an invalid error code.  Make sure it
  701. returns an error listed in Inside Macintosh VI.  It╒s not clear why this
  702. would cause a bus error, but it seemed to do so in an early version of
  703. Dragonsmith.
  704.  
  705.  
  706. ------------------------------------------------------
  707. NOTES ON APPLE EVENTS
  708. ------------------------------------------------------
  709.  
  710. Any application which is high level event aware will receive exactly one of
  711. the three following kinds of events when launched by the Finder:
  712.  
  713. Open Application
  714. If this event is received, the user double-clicked on the
  715. application in the Finder, or selected the application and chose ╘Open╒ from
  716. the File menu.
  717.  
  718. Open Documents
  719. If this event is received, the user double-clicked on a file
  720. (or group of files) belonging to the application, or selected the file(s)
  721. and chose ╘Open╒ from the File menu, or drag-and-dropped it (or them) onto
  722. the application╒s icon.
  723.  
  724. Print Documents
  725. If this event is received, the user selected a file (or
  726. group of files) and chose ╘Print╒ from the File menu.
  727.  
  728. An application may receive any number of Open Documents and Print Documents
  729. from the Finder after it has started.
  730.  
  731. Other processes may launch an application with any kind of Apple event, or
  732. none at all, and may later send any kind and number of Apple events to it. 
  733. Because of this, your code should never rely on receiving any Apple events
  734. in any sequence.
  735.  
  736. QuitApplication
  737. The Finder will send a Quit Application event to an
  738. application if the user chooses ╘Restart╒ or ╘Shut Down╒ from the ╘Special╒
  739. menu (and possibly under other circumstances as well).  Other processes may
  740. send this event to the application at any time.
  741.  
  742.  
  743. ------------------------------------------------------
  744. HOW TO╔
  745. ------------------------------------------------------
  746.  
  747. Automatic disk and folder opening
  748.  
  749. To make your dragon automatically process files inside directories (i.e.,
  750. volumes and folders), change the value of dirDepthLimit (in your constructor
  751. as well as in the ╘DrPr╒ 128 resource) to a negative number indicating how
  752. many levels down your dragon will look.  This feature can be very handy, but
  753. it can also be very dangerous.  To avoid stack overflow, you should not set
  754. dirDepthLimit to a value less than about -100.  If you set resolveAliases =
  755. TRUE, then the possibility of recursion becomes an issue.
  756.  
  757. Figure 2 shows a hierarchical view of the contents of a folder
  758. ╘Miscellaneous╒ ╤ the depth of each file or folder (except 0 Another File
  759. alias) is indicated by the number its name begins with.  How your dragon
  760. should set its instance variables (and the corresponding values in its
  761. ╘DrPr╒ 129 resource) depends on what action you want it to take when the
  762. user drag-and-drops the hilited files on it.  (For the sake of this example,
  763. it╒s assumed that your dragon has ╘FREF╒ resources for types ╘fold╒ and
  764. ╘TEXT╒ and that all the files pictured are text files.)
  765.  
  766.     <Figure 2 omitted>
  767.  
  768. Table 1 gives details on which combinations of values will result in a
  769. particular set of documents being processed.  In several cases, the value of
  770. one or two instance variables is irrelevant.
  771.  
  772.     <Table 1 omitted>
  773.  
  774. Adding a menu
  775.  
  776. Refer to the file ╘MenusTmpl.c╒ for a simple illustration of how to add
  777. menus to your dragon.  The information below on adding a preferences setting
  778. also shows how to add a menu.
  779.  
  780. Adding a preference setting
  781.  
  782. The ╘PrefsTmpl.c╒ file contains sample code showing you how to implement
  783. preferences in Dragonsmith.  By default, every dragon will use a preferences
  784. file, whether it needs it or not ╤ to prevent your dragon from finding or
  785. creating a preferences file, put a null string in the ╘STR ╒ 128 resource
  786. and remove the ╘FREF╒ resource for the type designated by the instance
  787. variable prefsFileType.
  788.  
  789. The ╘PrRo╒ 128 resource in your dragon╒s preferences (and application) file
  790. contains references to the preferences resources which belong to it.  The
  791. first resource designated in the ╘PrRo╒ 128 resource must be ╘DrPr╒ 128,
  792. which contains several important values used by every Dragon subclass (see
  793. below).
  794.  
  795. Documentation for the Preferences class is minimal in this release of
  796. Dragonsmith ╤ a later release will correct that.  In the mean time, reading
  797. the source code for the class may be instructive.
  798.  
  799. The steps involved in adding a new preference to your dragon are as follows:
  800.  
  801.     Ñ Add a resource in your project resource file to hold the preferences
  802. value(s)
  803.  
  804.     Ñ Create an entry for the added preferences resource at the end of the
  805. ╘PrRo╒ 128 resource in your project resource file
  806.  
  807.     Ñ Add an instance variable to hold a handle to the added resource
  808.  
  809.     Ñ Add instance variables to your Dragon subclass to hold the values from
  810. your added resource
  811.  
  812.     Ñ In your dragon╒s constructor method, initialize the preferences instance
  813. variables to safe, if-all-else-fails default values ╤ your dragon should not
  814. crash or abort if some preferences couldn╒t be found
  815.  
  816.     Ñ Override ReadPrefs as indicated below
  817.  
  818.     Ñ Add some way in your dragon╒s interface to change the additional
  819. preference(s)
  820.  
  821.     Ñ Add code to change the preferences resource in memory and save it to disk
  822.  
  823. As an example, take the case of a dragon (named ╘Scruncher╒) that uses one
  824. of three compression methods (Fast, Normal, or Tight) to compact files.  The
  825. user can choose any one of the three, and may also specify whether Finder
  826. information about the file is preserved in the resulting archive.  These
  827. preferences are stored in a ╘ScPr╒ 128 resource in the Scruncher.╣.rsrc
  828. file.  Figure 3 shows the dragon╒s added menu:
  829.  
  830.     <Figure 3 omitted>
  831.  
  832. The DScruncher.c file would look something like this:
  833.  
  834. #include    "Dragon.h"
  835. #include    ╥MenuUtils.h╙
  836. #include    ╥Preferences.h╙
  837. #define    prefScruncherPrefs    prefDragonPrefs + 1
  838. enum {
  839.     mOptions = mEdit + 1
  840. };
  841. enum {
  842.     iFastScrunching,
  843.     iNormalScrunching,
  844.     iSmallScrunching,
  845.     iLine3,
  846.     iSaveFInfo
  847. };
  848.     
  849. typedef struct {
  850.     char        scrunchType;
  851.     Boolean    saveFInfo;
  852. } ScrunchOpts;
  853.  
  854. class DScruncher : public Dragon {
  855.  
  856.     protected:
  857.         ScrunchOpts    **scrunchOptions;
  858.         char        scrunchType;
  859.         Boolean        saveFInfo;
  860.         
  861.     public:
  862.                     DScruncher (void);    // Constructor
  863.                     
  864.     protected:
  865.         [Protected method declarations omitted for brevity]
  866. };
  867.  
  868. Dragon *CreateGDragon (void)
  869. {
  870.     return (Dragon *) new DScruncher;
  871. }
  872.  
  873. DScruncher::DScruncher (void)
  874. {
  875.     optionsMenu = NULL;
  876.     scrunchOptions = NULL;
  877.     scrunchType = iNormalScrunching;
  878.     saveFInfo = TRUE;
  879. }
  880.  
  881. void DScruncher::ReadPrefs (void)
  882. {
  883.     inherited::ReadPrefs ();
  884.  
  885.     scrunchOptions = (ScrunchOpts **) preferences->GetPrefResource
  886.             (prefFilePathOptions);
  887.  
  888.     if (scrunchOptions != NULL) {
  889.         HNoPurge ((Handle) scrunchOptions);
  890.         scrunchType = scrunchOptions->scrunchType;
  891.         saveFInfo = scrunchOptions->saveFInfo;
  892.     }
  893. }
  894.  
  895. void DScruncher::SetUpMenus (void)
  896. {
  897.     inherited::SetUpMenus ();        // Add the Apple, File, and Edit menus
  898.  
  899.     optionsMenu = GetMenu (mOptions);
  900.     InitOptionsMenu ();
  901.     InsertMenu (optionsMenu, 0);
  902.  
  903.     DrawMenuBar ();
  904. }
  905.  
  906. void DScruncher::InitOptionsMenu (void)
  907. {
  908.     // Initialize options menu (and set the options while we╒re at it)
  909.     CheckItem (optionsMenu, iSaveFInfo, saveFInfo);
  910.     SetScrunchType (iFastScrunching + scrunchType - 1);
  911. }
  912.  
  913. void DScruncher::DoMenu (long menuItemCode)
  914. {
  915.     if (menuItemCode >> 16 == mOptions)
  916.         DoOptionsMenu (menuItemCode & 0xFFFF);
  917.     else
  918.         inherited::DoMenu (menuItemCode);
  919. }
  920.  
  921. void DScruncher::DoOptionsMenu (short itemNum)
  922. {
  923.     if (itemNum == iSaveFInfo)
  924.         ToggleSaveFInfo ();
  925.     else
  926.         SetScrunchType (itemNum);
  927.  
  928.     // Save any changes that might have been made
  929.     preferences->SavePrefResource (prefFilePathOptions);
  930. }
  931.  
  932. void DScruncher::ToggleSaveFInfo (void)
  933. {
  934.     saveFInfo = ToggleMenuItem (optionsMenu, iSaveFInfo);
  935.     if (scrunchOptions)
  936.         (*scrunchOptions)->saveFInfo = saveFInfo;
  937. }
  938.  
  939. void DScruncher::SetScrunchType (short scrunchItem)
  940. {
  941.     CheckOne (optionsMenu, iFastScrunching, iSmallScrunching, scrunchItem);
  942.     scrunchType = scrunchItem;
  943.     if (scrunchOptions)
  944.         (*scrunchOptions)->scrunchType = scrunchType;
  945. }
  946.  
  947. void DFilePaths::AdjustMenusBusy (void)
  948. {
  949.     inherited::AdjustMenusBusy ();
  950.     DisableItem (optionsMenu, 0);        // Disable the Options menu
  951. }
  952.  
  953. void DFilePaths::AdjustMenusIdle (void)
  954. {
  955.     inherited::AdjustMenusIdle ();
  956.     EnableItem (optionsMenu, 0);        // Enable the options menu
  957. }
  958.  
  959.  
  960. ------------------------------------------------------
  961. DRAGONS AHOY!
  962. ------------------------------------------------------
  963.  
  964. Here╒s a list of some dragons that have been spotted by the author on the
  965. (albeit distant) horizon:
  966.  
  967. Drawk
  968. ╘Load╒ an awk program, then drag-and-drop input files.
  969.  
  970. D. D. Rex
  971. Specify text substitutions using grep syntax, then drag-and-drop
  972. files to make the changes in ╤ something like Paradigma, but with grep
  973. capability.
  974.  
  975. Proto Drake
  976. Make function and method prototype files from drag-and-dropped C
  977. source files.
  978.  
  979. Icon Elephant
  980. Tired of the Finder spontaneously rearranging your windows╒
  981. icons under mysterious circumstances, after you spent five minutes getting
  982. the icons just right?  Drag-and-drop a folder on Icon Elephant to restore
  983. ╘remembered╒ icon positions on demand.
  984.  
  985. Dragon Deity
  986. Create Dragonsmith source code and related files quickly and
  987. easily; check projects and their resource files for consistency,
  988. completeness, and general good health.
  989.  
  990. THINK╩C Thief
  991. Drag-and-drop THINK╩C 5.0 projects to discover what files they
  992. contain, and more.
  993.  
  994.  
  995. ------------------------------------------------------
  996. DRAGON INSTANCE VARIABLES
  997. ------------------------------------------------------
  998.  
  999. Most of the instance variables described below should normally not be
  1000. altered by subclasses of Dragon.  Instance variables whose values are set in
  1001. ReadPrefs (from the ╘DrPr╒╩128 resource) are noted.
  1002.  
  1003. abortProcessing
  1004.  
  1005. Boolean abortProcessing;
  1006.  
  1007. Don╒t change the value of this instance variable directly ╤ call
  1008. StopProcessing instead
  1009.  
  1010. This flag will be set to TRUE if a serious error prevents the current Open
  1011. Documents from continuing, or if the user cancels processing by pressing
  1012. Command╨period.
  1013.  
  1014. acceptableTypes
  1015.  
  1016. TypeListHndl acceptableTypes;
  1017.  
  1018. Don╒t change the value of this instance variable or the data it points to
  1019.  
  1020. This is a handle to a list of document types (taken from your dragon╒s
  1021. ╘FREF╒ resources) that your dragon knows how to process.
  1022.  
  1023. aeQueue
  1024.  
  1025. AppleEventQueue *aeQueue;
  1026.  
  1027. Don╒t change the value of this instance variable
  1028.  
  1029. This is a reference to an instance of class AppleEventQueue, which is used
  1030. to manage a simple FIFO queue of Open Documents events received while your
  1031. dragon is processing documents from a previous event.
  1032.  
  1033. appFile
  1034.  
  1035. FSSpec appFile;
  1036.  
  1037. Don╒t change the value of this instance variable
  1038.  
  1039. This contains an FSSpec to your application ╤ it╒s set in the Dragon class╒s
  1040. constructor and can be used in any way you want.
  1041.  
  1042. appleMenu
  1043.  
  1044. MenuHandle appleMenu;
  1045.  
  1046. Don╒t change the value of this instance variable
  1047.  
  1048. This is a handle to the standard Apple menu implemented by the Dragon class.
  1049.  
  1050. appResFork
  1051.  
  1052. short appResFork;
  1053.  
  1054. Don╒t change the value of this instance variable
  1055.  
  1056. This instance variable contains a refNum to the resource fork of your dragon
  1057. ╤ it╒s the access path created by the system when the application is
  1058. launched.
  1059.  
  1060. Note:    When running in the THINK╩C Debugger, appResFork is actually a refNum
  1061. to the project resource file.  The effect in either case is identical.
  1062.  
  1063. autoQuit
  1064.  
  1065. Boolean autoQuit;
  1066.  
  1067. Will be set in ReadPrefs
  1068.  
  1069. This instance variable determines whether your dragon will terminate after
  1070. processing the first Apple event it receives ╤ DoOapp, DoOdoc, and DoPdoc
  1071. all test the value in autoQuit.  Also, because an auto-quit dragon won╒t
  1072. have any use for menus, the Start method will call SetUpMenus only if
  1073. autoQuit != FALSE.
  1074.  
  1075. busyCursor
  1076.  
  1077. CursHandle busyCursor;
  1078.  
  1079. This is a handle to the watch cursor (not animated) that is displayed (by
  1080. CursorBusy) when your dragon is processing documents in the foreground.
  1081.  
  1082. Note:    Cursor animation is planned for a later release of Dragonsmith.
  1083.  
  1084. curDirDepth
  1085.  
  1086. short curDirDepth;
  1087.  
  1088. Don╒t change the value of this instance variable
  1089.  
  1090. The depth at which your dragon is currently processing documents.  A depth
  1091. of 0 indicates that the current document was specified in an Open Documents
  1092. event your dragon received.  A depth of -1 indicates that the current
  1093. document is located immediately inside a folder or disk specified in an Open
  1094. Documents event.
  1095.  
  1096. curDocFSS
  1097.  
  1098. FSSpec *curDocFSS;
  1099.  
  1100. Don╒t change the value of this instance variable; you can change the data to
  1101. which it points
  1102.  
  1103. Pointer to an FSSpec designating the current document.  The data in
  1104. *curDocFSS is meaningful only while your dragon is processing documents.
  1105.  
  1106. curDocPB
  1107.  
  1108. PBRecUnion *curDocPB;
  1109.  
  1110. Don╒t change the value of this instance variable; you can change the data to
  1111. which it points
  1112.  
  1113. This is a pointer to a PBRecUnion designating the current document.  A
  1114. PBRecUnion is a union of the six parameter blocks used in making low-level
  1115. File Manager calls.  The data in *curDocPB is meaningful only while your
  1116. dragon is processing documents.  Your dragon is free to change, in the
  1117. ProcessFile and ProcessDirectory methods, any of the data to which curDocPB
  1118. points.  If it does so, it can call SaveDocInfo to make the changes
  1119. permanent and (optionally) refresh the Finder╒s display of the window
  1120. containing the document in order to make the changes visible to the user.
  1121.  
  1122. If you╒re unfamiliar with the low-level File Manager routines and their
  1123. various parameter blocks, you can safely ignore curDocPB altogether ╤ or you
  1124. can use the macros defined in Dragon.h and described in the section Macros
  1125. to access fields in curDocPB without having to understand how the macros
  1126. work.
  1127.  
  1128. Warning:    Use of these macros can be tricky.  Make sure that you understand
  1129. when it is and is not safe to use them.
  1130.  
  1131. cursorRgn
  1132.  
  1133. RgnHandle cursorRgn;
  1134.  
  1135. This instance variable is used as a parameter to WaitNextEvent.  The Dragon
  1136. class sets it to NULL.  Your dragon should allocate a region in cursorRgn if
  1137. it uses mouse-moved events.
  1138.  
  1139. dirDepthLimit
  1140.  
  1141. short dirDepthLimit;
  1142.  
  1143. Will be set in ReadPrefs
  1144.  
  1145. The depth (a negative value) to which your dragon will look inside nested
  1146. directories in search of documents to process.  The depth of each of the
  1147. documents drag-and-dropped on your dragon is 0, so if dirDepthLimit is 0,
  1148. then your dragon will only see the documents specified in the Open Documents
  1149. event.
  1150.  
  1151. Warning:    Recursive (but not infinitely recursive) directory scanning may
  1152. occur if dirDepthLimit < 0 and resolveAliases╩==╩TRUE.  For more
  1153. information, read the section Automatic disk and folder opening above.  Even
  1154. if resolveAliases == FALSE, because of the danger of stack overflow your
  1155. dragon should not set dirDepthLimit lower than about ╨50.  (Every recursion
  1156. of ProcessDocsInDirectory requires 70 bytes on the stack, so this would
  1157. consume 3500 bytes.)
  1158.  
  1159. dragonPrefs
  1160.  
  1161. DragonPrefsRec **dragonPrefs;
  1162.  
  1163. Don╒t change the value of this instance variable
  1164.  
  1165. The values in dragonPrefs are read from the ╘DrPr╒ 128 resource (in
  1166. ReadPrefs) and are used to set the following instance variables:
  1167.  
  1168. filesOnly    sleepValue[0..3]
  1169.  
  1170. resolveAliases    sleepTime
  1171.  
  1172. followAliasChain    dirDepthLimit
  1173.  
  1174. autoQuit
  1175.  
  1176. editMenu
  1177.  
  1178. MenuHandle editMenu;
  1179.  
  1180. Don╒t change the value of this instance variable
  1181.  
  1182. This is a handle to the standard Edit menu implemented by the Dragon class.
  1183.  
  1184. fileMenu
  1185.  
  1186. MenuHandle fileMenu;
  1187.  
  1188. Don╒t change the value of this instance variable
  1189.  
  1190. This is a handle to the minimal File menu (containing a single Quit item)
  1191. implemented by the Dragon class.
  1192.  
  1193. filesOnly
  1194.  
  1195. Boolean filesOnly;
  1196.  
  1197. Will be set in ReadPrefs
  1198.  
  1199. The value of filesOnly is tested only when all of the following are true:
  1200.  
  1201.     Ñ Your dragon has an ╘FREF╒ resource for the document type ╘fold╒ or ╘disk╒
  1202.  
  1203.     Ñ Your dragon encounters a directory at the maximum depth (curDirDepth ==
  1204. dirDepthLimit)
  1205.  
  1206.     Ñ useCustomFilter == FALSE or the directory passes the CustomFilterDoc test
  1207.  
  1208. Under these circumstances, ProcessDirectory will be executed only if
  1209. filesOnly is FALSE.  This instance variable should be set to TRUE if you
  1210. want to ensure that ProcessDirectory will never be called.  See the How to╔
  1211. section for more information on what combination of values to use to achieve
  1212. a particular drag-and-drop effect.
  1213.  
  1214. Note:    It doesn╒t make sense to add ╘FREF╒ resources for ╘disk╒ and ╘fold╒
  1215. types, then set dirDepthLimit to 0 and filesOnly to TRUE.
  1216.  
  1217. followAliasChain
  1218.  
  1219. Boolean followAliasChain;
  1220.  
  1221. Will be set in ReadPrefs
  1222.  
  1223. This instance variable is only meaningful if resolveAliases == TRUE. 
  1224. Normally, followAliasChain should be TRUE ╤ if not, then an alias file at
  1225. the beginning of an alias chain will only be resolved one step of the way
  1226. rather than all the way to the original document.
  1227.  
  1228. menusInstalled
  1229.  
  1230. Boolean menusInstalled;
  1231.  
  1232. Don╒t change the value of this instance variable
  1233.  
  1234. This instance variable will be set to TRUE as soon as your dragon╒s menus
  1235. have been installed.  Several Dragon methods rely on the value of
  1236. menusInstalled to avoid a crash.
  1237.  
  1238. numAEsPending
  1239.  
  1240. short numAEsPending;
  1241.  
  1242. Don╒t change the value of this instance variable
  1243.  
  1244. This is the number of outstanding Apple events tracked by the aeQueue
  1245. object.
  1246.  
  1247. preferences
  1248.  
  1249. Preferences *preferences;
  1250.  
  1251. Don╒t change the value of this instance variable
  1252.  
  1253. This is a reference to an instance of class Preferences, used to manage the
  1254. dragon╒s preferences.
  1255.  
  1256. Note:    If you don╒t want your dragon to use a preferences file, you should
  1257. not alter (or delete) this object ╤ set the ╘STR ╒ 128 resource to "\p"
  1258. instead (and delete the ╘FREF╒ for type prefsFileType).  The preferences
  1259. object is used to manage preferences, not just a preferences file.
  1260.  
  1261. prefsFileType
  1262.  
  1263. OSType prefsFileType;
  1264.  
  1265. This is the file type of your dragon╒s preferences file.  The System 7
  1266. Finder supplies a generic icon for files of type ╘pref╒, and that╒s the
  1267. value that Dragon uses.
  1268.  
  1269. resolveAliases
  1270.  
  1271. Boolean resolveAliases;
  1272.  
  1273. Will be set in ReadPrefs
  1274.  
  1275. The value of this instance variable determines whether your dragon will
  1276. automatically resolve alias files that it encounters while processing
  1277. documents from an ╘odoc╒ event.  Normally, alias files will only be found
  1278. inside a drag-and-dropped directory, when dirDepthLimit < 0 ╤ the Finder
  1279. automatically resolves alias files before putting them in the event╒s list
  1280. of documents.  An Open Documents event sent by any other application,
  1281. however, may contain references to alias files.
  1282.  
  1283. Warning:    You should not set resolveAliases = TRUE (in your dragon╒s
  1284. constructor or in its ╘DrPr╒ 128 resource) unless either of these two
  1285. conditions is true:
  1286.  
  1287.     Ñ Nothing ╘bad╒ will happen if your dragon processes the same file more
  1288. than once.
  1289.  
  1290.     Ñ Your dragon can tell if it╒s already processed a file.
  1291.  
  1292. One way to make sure you don╒t process the same file twice would be to call
  1293. TickCount in your dragon╒s BeginProcessing method, keep the result in an
  1294. instance variable, and store this value in a resource (say, ╘PTix╒ 128) in
  1295. every file that╒s processed.  Then a simple check (in CustomFilterDoc,
  1296. probably) of this resource for each file your dragon gets will ensure that
  1297. nothing gets processed twice.  The only problem with this approach is that
  1298. would slow things down considerably.
  1299.  
  1300. Even if your dragon does not set resolveAliases = TRUE, there╒s no guarantee
  1301. that it won╒t process the same file twice ╤ the user might well
  1302. drag-and-drop a file and an alias to the same file simultaneously.  You
  1303. shouldn╒t worry too much about this possibility, since there╒s very little
  1304. you can do about it.
  1305.  
  1306. running
  1307.  
  1308. Boolean running;
  1309.  
  1310. Don╒t change the value of this instance variable directly ╤ call StopRunning
  1311. instead
  1312.  
  1313. This flag is TRUE as long as your dragon is running.  It will be set to
  1314. FALSE in StopRunning to cause your dragon to quit (by ╘falling╒ out of the
  1315. main event loop in Run).
  1316.  
  1317. runState
  1318.  
  1319. short runState;
  1320.  
  1321. Don╒t change the value of this instance variable
  1322.  
  1323. The low two bits of this instance variable designate the current state of
  1324. your dragon.  The following masks can be used to read these flags:
  1325.  
  1326. maskInBG    0x0001    Indicates the dragon is running in the background 
  1327.  
  1328. maskBusy     0x0002    Indicates the dragon is processing documents
  1329.  
  1330. This instance variable is maintained for your dragon by the Dragon class╒s
  1331. constructor and its BeginProcessing, EndProcessing, DoSuspend, and DoResume
  1332. methods.
  1333.  
  1334. signature
  1335.  
  1336. OSType signature;
  1337.  
  1338. Don╒t change the value of this instance variable
  1339.  
  1340. This is your dragon╒s application signature.  You should assign unique
  1341. signatures to the dragons you create and register each with Apple.
  1342.  
  1343. sleepTime
  1344.  
  1345. long sleepTime;
  1346.  
  1347. This instance variable is used as a parameter to WaitNextEvent to indicate
  1348. the maximum number of ticks your dragon will relinquish to other processes. 
  1349. Its value is maintained by the Dragon class╒s constructor and its
  1350. BeginProcessing, EndProcessing, DoSuspend, DoResume, and ReadPrefs methods.
  1351.  
  1352. sleepValue[4]
  1353.  
  1354. long sleepValue[4];
  1355.  
  1356. Will be set in ReadPrefs
  1357.  
  1358. The four values in this instance variable denote the possible values for
  1359. sleepTime when indexed by the low two bits of runState.
  1360.  
  1361. useCustomFilter
  1362.  
  1363. Boolean useCustomFilter;
  1364.  
  1365. Set useCustomFilter to TRUE if your dragon╒s CustomFilterDoc method is used
  1366. to filter out unwanted documents.
  1367.  
  1368.  
  1369. ------------------------------------------------------
  1370. DRAGON METHODS
  1371. ------------------------------------------------------
  1372.  
  1373. Each method description is preceded by its declaration (from the body of the
  1374. Dragon class declaration in Dragon.h).  Many of the methods have
  1375. restrictions on how a subclass should or should not override them.  ╘Do not
  1376. override╒ should not be taken as an absolute; it simply means that you
  1377. should have a thorough understanding of what the method does in Dragon (and
  1378. why) before you override it.  There are a few more explicit warnings as well
  1379. ╤ these should be taken a bit more seriously.
  1380.  
  1381. Abort
  1382.  
  1383. virtual void Abort (short errNum);
  1384.  
  1385. Abort is called whenever a serious error occurs that prevents execution of
  1386. the dragon application from continuing.  This method displays an error alert
  1387. terminates the program.
  1388.  
  1389. Warning:    Your dragon should be very careful about calling Abort ╤ in
  1390. general, you should avoid calling it any time after the Start method has
  1391. completed execution.
  1392.  
  1393. AdjustMenusBusy
  1394.  
  1395. virtual void AdjustMenusBusy (void);
  1396.  
  1397. Call inherited::AdjustMenusBusy if you override this method
  1398.  
  1399. This method disables any menu items that the user must not be able to select
  1400. while the dragon is processing documents ╤ notably, Quit.  It does not
  1401. disable the Apple menu.  If your dragon has any additional menus (or menu
  1402. items), you should override this method to avoid leaving any dangerous items
  1403. enabled while the dragon is ╥busy.╙
  1404.  
  1405. AdjustMenusIdle
  1406.  
  1407. virtual void AdjustMenusIdle (void);
  1408.  
  1409. Call inherited::AdjustMenusIdle if you override this method
  1410.  
  1411. This method is the converse of AdjustMenusBusy ╤ it restores any menu items
  1412. that were disabled when the dragon began processing documents.
  1413.  
  1414. BeginProcessing
  1415.  
  1416. virtual void BeginProcessing (void);
  1417.  
  1418. Call inherited::BeginProcessing if you override this method
  1419.  
  1420. BeginProcessing is called by ProcessDroppings before any drag-and-dropped
  1421. documents are processed.  Its default behavior in Dragon is to disable any
  1422. menu items that must not be called while processing is going on, then put up
  1423. a ╥busy╙ cursor.
  1424.  
  1425. CallMoreMasters
  1426.  
  1427. virtual void CallMoreMasters (void);
  1428.  
  1429. CallMoreMasters calls MoreMasters the number of times specified in the
  1430. ╘MoMa╒ 128 resource (as described below) in order to allocate additional
  1431. master pointers.  The resource files provided in the folder ╘Template Files╒
  1432. all contain a value of 0 in the ╘MoMa╒ 128 resource.
  1433.  
  1434. CanProcessDoc
  1435.  
  1436. virtual Boolean CanProcessDoc (void);
  1437.  
  1438. Don╒t override
  1439.  
  1440. CanProcessDoc checks to make sure that the file or directory specified in
  1441. curDocFSS and curDocPB is of a type that could be drag-and-dropped on your
  1442. dragon and applies any special filtering you╒ve specified with
  1443. useCustomFilter and CustomFilterDoc.
  1444.  
  1445. CursorBusy
  1446.  
  1447. virtual void CursorBusy (void);
  1448.  
  1449. This method changes the cursor to a watch (not animated) to show that the
  1450. application is doing something.
  1451.  
  1452. Note:    Cursor animation is planned for a later release of Dragonsmith.
  1453.  
  1454. CursorIdle
  1455.  
  1456. virtual void CursorIdle (void);
  1457.  
  1458. This method changes the cursor to show that the application is idle.
  1459.  
  1460. CustomFilterDoc
  1461.  
  1462. virtual Boolean CustomFilterDoc (void);
  1463.  
  1464. Override if your dragon needs to perform any additional filtering of
  1465. documents beyond that provided by the Dragon class
  1466.  
  1467. The CustomFilterDoc method will be called by ProcessDoc if and only if
  1468. useCustomFilter != FALSE.  For example, if your dragon reads a C source file
  1469. and produces a header file with prototypes for the functions and methods
  1470. contained in it, then your CustomFilterDoc method will presumably filter out
  1471. any file whose type is not ╘TEXT╒ or whose name doesn╒t end with ╥.c╙.
  1472.  
  1473. Note:    Your CustomFilterDoc method can go ahead and call one of a number of
  1474. different document-handling methods, based on whatever criteria it chooses,
  1475. and then return FALSE to fool ProcessDoc into thinking that the document
  1476. shouldn╒t be processed at all.  If your dragon does this, however, you
  1477. should keep in mind that future versions of Dragonsmith may provide an
  1478. else-clause in ProcessDoc that takes some action if (it believes that) a
  1479. document could not be handled.
  1480.  
  1481. DoAbout
  1482.  
  1483. virtual void DoAbout (void);
  1484.  
  1485. Override this method if you want your dragon to display a splash window.
  1486.  
  1487. This method is executed when the user chooses the ╘About╔╒ item from the
  1488. Apple menu.  The default in the Dragon class is to do nothing.
  1489.  
  1490. DoActivate
  1491.  
  1492. virtual void DoActivate (EventRecord *theEvent);
  1493.  
  1494. Override this method if your dragon has windows
  1495.  
  1496. This method is called by DoEvent whenever an activate event occurs (when a
  1497. window is being activated, not deactivated).  Refer to Inside Macintosh
  1498. Volume VI, pages 5╨14 to 5╨17 for a description of the ╘SIZE╒ resource╒s
  1499. effect on activate events.
  1500.  
  1501. DoAppleMenu
  1502.  
  1503. virtual void DoAppleMenu (short itemNum);
  1504.  
  1505. Do not override
  1506.  
  1507. DoAppleMenu is called whenever the user chooses an item in the Apple menu.
  1508.  
  1509. DoBusy
  1510.  
  1511. virtual void DoBusy (void);
  1512.  
  1513. You shouldn╒t have to override this method (since you can override
  1514. ShowProgress instead); call inherited::DoBusy if you do
  1515.  
  1516. This method is the ╥busy╙ counterpart of DoIdle ╤ it╒s called when your
  1517. dragon is processing docs rather than when it has nothing to do.  The Dragon
  1518. class calls it (at the beginning of ProcessDoc) for each document to be
  1519. processed; your dragon can make additional calls to DoBusy in order to yield
  1520. CPU time to other processes and to let the user switch to another
  1521. application or cancel the document processing.  The Dragon class╒s DoBusy
  1522. method calls ShowProgress and WaitNextEvent (in that order).
  1523.  
  1524. Warning:    Your dragon should not call DoBusy at any time when cancellation by
  1525. the user, or a Quit Application event sent by another process, would cause
  1526. problems.  (It╒s up to you to determine what ╘problems╒ means╔)
  1527.  
  1528. DoDeactivate
  1529.  
  1530. virtual void DoActivate (EventRecord *theEvent);
  1531.  
  1532. Override this method if your dragon has windows
  1533.  
  1534. This method is called by DoEvent whenever an activate event occurs (when a
  1535. window is being deactivated, not activated).  Refer to Inside Macintosh
  1536. Volume VI, pages 5╨14 to 5╨17 for a description of the ╘SIZE╒ resource╒s
  1537. effect on activate events.
  1538.  
  1539. DoDiskInsert
  1540.  
  1541. virtual void DoDiskInsert (EventRecord *theEvent);
  1542.  
  1543. Do not override
  1544.  
  1545. This method is called by DoEvent whenever a disk insert event occurs. 
  1546. Dragon::DoDiskInsert handles the event in the usual way, calling DIBadMount
  1547. to give the user a chance to initialize the disk if it╒s damaged or not yet
  1548. initialized.
  1549.  
  1550. DoEditMenu
  1551.  
  1552. virtual void DoEditMenu (short itemNum);
  1553.  
  1554. Override this method if you add any items to your dragon╒s File menu.  Call
  1555. inherited::DoEditMenu if the item chosen isn╒t one of the added items.
  1556.  
  1557. This method is executed whenever the user selects an item in the Edit menu. 
  1558. Dragon::DoEditMenu implements the standard behavior of an Edit menu with
  1559. Undo, Cut, Copy, Paste, and Clear items (plus a dividing line between Undo
  1560. and Cut).
  1561.  
  1562. DoEvent
  1563.  
  1564. virtual void DoEvent (EventRecord *event);
  1565.  
  1566. Do not override
  1567.  
  1568. This is the main ╥switchboard╙ from which event handling is dispatched. 
  1569. Your dragon would have to override this method only if it wanted to treat
  1570. keyDown and autoKey events differently.
  1571.  
  1572. DoFileMenu
  1573.  
  1574. virtual void DoFileMenu (short itemNum);
  1575.  
  1576. Override this method if you add any items to your dragon╒s File menu.  Call
  1577. inherited::DoFileMenu if the item chosen isn╒t one of the added items.
  1578.  
  1579. This method is executed whenever the user selects an item in the File menu. 
  1580. The default behavior in Dragon::DoFileMenu simply checks to see if the item
  1581. chosen is the last item in the menu, and calls StopRunning if it is.
  1582.  
  1583. Warning:    If your File menu doesn╒t end with Quit, then you should override
  1584. this method and not call inherited::DoFileMenu.
  1585.  
  1586. DoHighLevelEvent
  1587.  
  1588. virtual void DoHighLevelEvent (EventRecord *theEvent);
  1589.  
  1590. Do not override
  1591.  
  1592. This method is called by DoEvent whenever a high level event occurs.  It
  1593. calls AEProcessAppleEvent if it╒s an Apple event, or DoOtherHLEvent if it╒s
  1594. not.
  1595.  
  1596. DoIdle
  1597.  
  1598. virtual void DoIdle (void);
  1599.  
  1600. Override this method if your dragon does some periodic task(s) while nothing
  1601. else is happening.
  1602.  
  1603. DoIdle is called by Run each time WaitNextEvent returns no event (or a null
  1604. event).  It╒s the ╥idle╙ counterpart of DoBusy, described above.
  1605.  
  1606. Note:    When overriding this method, keep in mind that your DoIdle will be
  1607. called only when your dragon is not processing any documents and no
  1608. already-received Apple events are waiting to be processed.  Your method can
  1609. rely on these facts to make assumptions about the dragon╒s state.
  1610.  
  1611. DoKeyDown
  1612.  
  1613. virtual void DoKeyDown (EventRecord *theEvent);
  1614.  
  1615. Call inherited::DoKeyDown if you override this method and your method
  1616. doesn╒t handle the event
  1617.  
  1618. This method is called by DoEvent whenever a keyDown or autoKey event occurs.
  1619.  It checks for command╨key combinations (those in the menus as well as
  1620. ╨period).
  1621.  
  1622. DoMenu
  1623.  
  1624. virtual void DoMenu (long menuItemCode);
  1625.  
  1626. Override this method if you add any menus to your dragon.  Call
  1627. inherited::DoMenu if the item chosen isn╒t in one of the added menus.
  1628.  
  1629. DoMenu is called in response to a mouseDown in the menu bar or command-key
  1630. menu equivalent.  
  1631.  
  1632. DoMouseDown
  1633.  
  1634. virtual void DoMouseDown (EventRecord *theEvent);
  1635.  
  1636. Override this method if your dragon has windows
  1637.  
  1638. This method is called by DoEvent whenever a mouseDown event occurs.
  1639.  
  1640. DoMouseUp
  1641.  
  1642. virtual void DoMouseUp (EventRecord *theEvent);
  1643.  
  1644. This method is called by DoEvent whenever a mouseUp event occurs.  You may
  1645. need to override this method if you override DoMouseDown.
  1646.  
  1647. DoOapp
  1648.  
  1649. virtual OSErr DoOapp (AppleEvent *theAppleEvent, AppleEvent *theReply,
  1650. long╩refcon);
  1651.  
  1652. This method is called when the user launches the dragon from the Finder by a
  1653. means other than drag-and-drop (i.e., by double-click, select and open, or
  1654. select and Cmd╨Down Arrow).  The default DoOapp method in Dragon just checks
  1655. to see if autoQuit ==╩TRUE and calls StopRunning if it is.
  1656.  
  1657. DoOdoc
  1658.  
  1659. virtual OSErr DoOdoc (AppleEvent *theAppleEvent, AppleEvent *theReply,
  1660. long╩refcon);
  1661.  
  1662. DoOdoc is called by the Apple event handler function HandleOdoc whenever the
  1663. dragon receives an Open Documents (╘odoc╒) event.  If the dragon is already
  1664. processing an Apple event, it calls SuspendAEvent and returns.  Otherwise,
  1665. it gives the list of documents in the keyDirectObject parameter of the Open
  1666. Documents event to ProcessDropping.  Finally, it checks to see if autoQuit
  1667. ==╩TRUE and calls StopRunning if it is.
  1668.  
  1669. DoOSEvent
  1670.  
  1671. virtual void DoOSEvent (EventRecord *theEvent);
  1672.  
  1673. Override this method if your dragon handles mouse-moved events or maintains
  1674. its own private scrap
  1675.  
  1676. This method is called by DoEvent whenever an OS event occurs.  It in turn
  1677. calls DoSuspend or Doresume.
  1678.  
  1679. DoOtherHLEvent
  1680.  
  1681. virtual void DoOtherHLEvent (EventRecord *theEvent);
  1682.  
  1683. Override this method if your dragon handles non-Apple event high level
  1684. events
  1685.  
  1686. This method is called by DoHighLevelEvent whenever a high level event that
  1687. is not an Apple event occurs.
  1688.  
  1689. DoPdoc
  1690.  
  1691. virtual OSErr DoPdoc (AppleEvent *theAppleEvent, AppleEvent *theReply,
  1692. long╩refcon);
  1693.  
  1694. DoPdoc will be called if the user (in the Finder) selects a file that
  1695. belongs to your dragon and chooses ╥Print╙ from the File menu.  Very few
  1696. dragons will need to override this method ╤ the default Dragon::DoPdoc
  1697. merely returns an error.  Like DoOapp and DoOdoc, it checks to see if
  1698. autoQuit ==╩TRUE and calls StopRunning if it is.
  1699.  
  1700. DoQuit
  1701.  
  1702. virtual OSErr DoQuit (AppleEvent *theAppleEvent, AppleEvent *theReply,
  1703. long╩refcon);
  1704.  
  1705. DoQuit calls StopRunning, which will set running = FALSE to terminate the
  1706. main event loop.
  1707.  
  1708. DoResume
  1709.  
  1710. virtual void DoResume (void);
  1711.  
  1712. Override this method if your dragon needs to perform any additional actions
  1713. when it moves to the background.
  1714.  
  1715. DoResume is called whenever your dragon receives a resume event. 
  1716. Dragon::DoResume adjusts the values of runState and sleepTime and, if the
  1717. dragon is busy processing documents, calls CursorBusy to show a busy cursor.
  1718.  
  1719. DoSuspend
  1720.  
  1721. virtual void DoSuspend (void);
  1722.  
  1723. Override this method and call inherited::DoSuspend if your dragon needs to
  1724. perform any additional actions when it moves to the background.
  1725.  
  1726. DoSuspend is called whenever your dragon receives a suspend event. 
  1727. Dragon::DoSuspend adjusts the values of runState and sleepTime and, if the
  1728. dragon is busy processing documents, calls CursorIdle to restore the
  1729. standard arrow cursor.
  1730.  
  1731. DoUpdateEvent
  1732.  
  1733. virtual void DoUpdateEvent (EventRecord *theEvent);
  1734.  
  1735. Override this method if your dragon has windows
  1736.  
  1737. This method is called by DoEvent whenever an update event occurs.
  1738.  
  1739. Dragon
  1740.  
  1741. Dragon (void);
  1742.  
  1743. This is the Dragon constructor, which is called when the gDragon object is
  1744. created (in main), before the constructor (if there is one) for your
  1745. subclass of Dragon.
  1746.  
  1747. EndProcessing
  1748.  
  1749. virtual void EndProcessing (void);
  1750.  
  1751. Call inherited::EndProcessing if you override this method
  1752.  
  1753. This method performs ╥housekeeping╙ tasks associated with the completion of
  1754. document processing ╤ it sets sleepTime to the appropriate value and calls
  1755. AdjustMenusIdle and CursorIdle.
  1756.  
  1757. Error
  1758.  
  1759. virtual void Error (short errNum);
  1760.  
  1761. The Error method displays a very simple alert showing a brief message and
  1762. the number passed in the errNum parameter.
  1763.  
  1764. FindPrefsFile
  1765.  
  1766. virtual Boolean FindPrefsFile (FSSpec *fss);
  1767.  
  1768. Do not override
  1769.  
  1770. This method looks for your dragon╒s preferences file (the name of which is
  1771. specified in your dragon╒s ╘STR╩╘ 128 resource).  It looks first in the same
  1772. folder that contains your dragon, then in the Preferences folder within the
  1773. System folder.  If necessary, it calls MakePrefsFile to create a new file.
  1774.  
  1775. Finish
  1776.  
  1777. virtual void Finish (void);
  1778.  
  1779. Call inherited::Finish if you override this method
  1780.  
  1781. Finish is called by main after the Run method has ended.  It╒s responsible
  1782. for any last-minute ╥clean-up╙ ╤ close any open files, delete temporary
  1783. files, remove trap patches, dispose of objects, etc.  The default behavior
  1784. in Dragon is to dispose of the preferences object, flush the Apple events
  1785. queue (returning errors in the reply events of any pending Apple events),
  1786. and dispose of the aeQueue object.
  1787.  
  1788. Warning:    If you override Finish, you must call inherited::Finish at the end
  1789. of your method.  If the code in Dragon::Finish is not executed, the current
  1790. preferences will not be saved and there is a possibility (of unknown
  1791. likelihood) that a crash will occur if there are any pending Apple events.
  1792.  
  1793. FlushAEventQueue
  1794.  
  1795. virtual void FlushAEventQueue (void);
  1796.  
  1797. Do not override
  1798.  
  1799. FlushAEventQueue is called by Finish when there any pending Apple events. 
  1800. It asks the aeQueue object for each of the pending Apple events, then calls
  1801. AEResumeTheCurrentEvent with a pointer to the ReturnEventNotHandled
  1802. function.  This tells the sender of each pending Apple event that the event
  1803. wasn╒t handled ╤ since Finish is the last code that is executed, there╒s no
  1804. possibility of handling any events at this point.
  1805.  
  1806. InitAppleEvents
  1807.  
  1808. virtual void InitAppleEvents (void);
  1809.  
  1810. Override this method if your dragon handles any additional Apple events
  1811.  
  1812. InitAppleEvents installs handlers for the four required Apple events, and
  1813. calls MakeAEQObject.
  1814.  
  1815. InitMac
  1816.  
  1817. virtual void InitMac (void);
  1818.  
  1819. Override this method and call inherited::InitMac (at the beginning of your
  1820. method) if your dragon requires more than the usual initializations.
  1821.  
  1822. InitMac initializes the usual system software managers.  Dragon::InitMac
  1823. calls InitGraf, InitFonts, InitWindows, InitMenus, TEInit, InitDialogs, and
  1824. InitCursor (in that order).
  1825.  
  1826. InitMem
  1827.  
  1828. virtual void InitMem (void);
  1829.  
  1830. Override this method if you want to increase the amount of memory allotted
  1831. to your dragon╒s stack
  1832.  
  1833. InitMem enlarges your dragon╒s application zone to its maximum size and
  1834. calls CallMoreMasters.
  1835.  
  1836. InitMilieu
  1837.  
  1838. virtual void InitMilieu (void);
  1839.  
  1840. Do not override this method ╤ add to the ╘GChk╒ resource instead
  1841.  
  1842. InitMilieu checks your dragon╒s run-time environment against the
  1843. specifications in the ╘GChk╒ 128 resource (as described below), and calls
  1844. Abort with an appropriate error code if the run-time environment is not
  1845. sufficient to run your dragon.  Otherwise, it calls InitAppleEvents.
  1846.  
  1847. InitPrefs
  1848.  
  1849. virtual void InitPrefs (void);
  1850.  
  1851. Do not override
  1852.  
  1853. This method creates and initializes the preferences object, asks
  1854. FindPrefsFile to look for a preferences file, and (if one is found or
  1855. created) tells the preferences object to use that file.  If the preferences
  1856. file had to be created, then the appropriate preferences resources will be
  1857. copied to it from the dragon╒s application file.  InitPrefs ends by calling
  1858. ReadPrefs to read in the preferences from the file╒s resources.
  1859.  
  1860. InteractWithUser
  1861.  
  1862. virtual Boolean InteractWithUser (long timeOut);
  1863.  
  1864. Do not override
  1865.  
  1866. Your dragon should call this method if it needs to interact with the user
  1867. (by putting up a dialog, for example) while it╒s processing documents. 
  1868. InteractWithUser calls the Toolbox routine AEInteractWithUser using an idle
  1869. function (CallWaitIdle, described below) that ensures that events will be
  1870. processed normally while idling.
  1871.  
  1872. The timeOut parameter is the number of ticks your dragon is willing to wait
  1873. for the user to bring the dragon to the foreground.  A reasonable value for
  1874. timeOut might fall between 600 and 7200 ticks (10 seconds and 2 minutes).
  1875.  
  1876. IsPrefsFile
  1877.  
  1878. virtual Boolean IsPrefsFile (FSSpec *fss);
  1879.  
  1880. Do not override
  1881.  
  1882. This method checks the file specified by fss to make sure it has the proper
  1883. creator and type to be your dragon╒s preferences file.
  1884.  
  1885. Note:    IsPrefsFile does not test the validity of the file╒s resources ╤ that
  1886. responsibility falls to the VerifyResources method of your subclass of the
  1887. Preferences class, if you choose to make one.
  1888.  
  1889. MakeAEQObject
  1890.  
  1891. virtual AppleEventQueue *MakeAEQObject (void);
  1892.  
  1893. Override this method if you implement a subclass of AppleEventsQueue
  1894.  
  1895. MakeAEQObject creates, and returns a reference to, an instance of class
  1896. AppleEventsQueue(or of a subclass of AppleEventsQueue, if you override this
  1897. method).
  1898.  
  1899. MakePrefsFile
  1900.  
  1901. virtual Boolean MakePrefsFile (FSSpec *fss);
  1902.  
  1903. Do not override
  1904.  
  1905. This method creates a new preferences file, as specified by fss.  It does
  1906. not add any resources to the file.
  1907.  
  1908. MakePrefsObject
  1909.  
  1910. virtual Preferences  *MakePrefsObject (void);
  1911.  
  1912. Override this method if you implement a subclass of Preferences
  1913.  
  1914. MakePrefsObject creates, and returns a reference to, an instance of class
  1915. Preferences (or of a subclass of Preferences, if you override this method).
  1916.  
  1917. ProcessDirectory
  1918.  
  1919. virtual void ProcessDirectory (void);
  1920.  
  1921. Your dragon should override this method if it processes directories (folders
  1922. and volumes) themselves rather than their contents (files and other
  1923. directories).
  1924.  
  1925. ProcessDirectory will be executed only when ╤
  1926.  
  1927. ( filesOnly == FALSE
  1928.   && curDocIsDirectory      // it's a folder or disk
  1929.   && curDirDepth == dirDepthLimit
  1930.   && CanProcessDoc () )
  1931.  
  1932. Here are some examples of the functionality of dragons that would need to
  1933. override ProcessDirectory:
  1934.  
  1935.     Ñ Show information about a disk [presumably more that what the Finder╒s
  1936. ╥Get Info╙ gives you]
  1937.     Ñ Scan a folder (or folders) for new files dropped in it (or them), then
  1938. call ProcessFile for each such file (for example, to monitor incoming mail
  1939. or expand files [this is essentially what DownLine does]
  1940.     Ñ Copy the full paths of selected directories (and files) to the clipboard
  1941. [this is what FilePaths does]
  1942.  
  1943. ProcessDoc
  1944.  
  1945. virtual void ProcessDoc (void);
  1946.  
  1947. Don╒t override
  1948.  
  1949. This method (which should normally not be overridden) is the ╥bottleneck╙
  1950. through which all documents must pass before they can be processed.  It
  1951. begins by checking to see that the document specified by curDocFSS and
  1952. curDocPB (both of which are valid at this point) is of a kind that could be
  1953. drag-and-dropped on your dragon, then applies any special filtering that you
  1954. may have set up in CustomFilterDoc.  If the document meets those
  1955. requirements, ProcessDoc passes it as follows:
  1956.  
  1957.     Ñ If the document is a file belonging to your dragon (curDocIsFile &&
  1958. curDocCreator ==╩this->signature), then it╒s passed to ProcessOwnedFile.
  1959.     Ñ If the document is a file that does not belong to your dragon, then it╒s
  1960. passed to ProcessFile ╤ this is the usual case.
  1961.     Ñ If the document is a folder or volume and the maximum level of folder
  1962. opening (see the descriptions of curDirDepthLimit and dirDepthLimit in the
  1963. Instance Variables section) has not yet been reached, then it╒s passed to
  1964. ProcessDocsInDirectory, which will process the documents inside the folder
  1965. (or volume).
  1966.     Ñ If the document is a folder or volume at the maximum level of folder
  1967. opening, and if your dragon sets filesOnly = FALSE, then it will be passed
  1968. to ProcessDirectory.
  1969.  
  1970. ProcessDocsInDirectory
  1971.  
  1972. virtual void ProcessDocsInDirectory (short vRefNum, long dirID);
  1973.  
  1974. Don╒t override
  1975.  
  1976. This method looks through the current directory and, for each thing it finds
  1977. there, sets up curDocFSS and curDocPB and calls ProcessDoc.
  1978.  
  1979. ProcessDroppings
  1980.  
  1981. virtual OSErr ProcessDroppings (AEDescList *docList);
  1982.  
  1983. ProcessDroppings loops through the documents that were drag-and-dropped on
  1984. your application and calls ProcessDoc for each one after setting up
  1985. curDocFSS and curDocPB.  Alias files are resolved here (if resolveAliases !=
  1986. FALSE).  ProcessDroppings calls BeginProcessing before handling the first
  1987. document and EndProcessing after the last.
  1988.  
  1989. ProcessFile
  1990.  
  1991. virtual void ProcessFile (void);
  1992.  
  1993. Override except in unusual cases
  1994.  
  1995. ProcessFile is the heart of any typical sub-class of Dragon.  Unless your
  1996. dragon only handles volumes or folders, you will certainly need to override
  1997. this method ╤ this is where the actual work is done (or the methods that do
  1998. the work are called).
  1999.  
  2000. ProcessOwnedFile
  2001.  
  2002. virtual void ProcessOwnedFile (void);
  2003.  
  2004. Override if your dragon creates any special file types (other than
  2005. preferences files) and treats them differently than it does files which it
  2006. didn╒t create
  2007.  
  2008. The default behavior for ProcessOwnedFile is to check if the file designated
  2009. by curDocFSS and curDocPB is a preferences file and, if it is, to use the
  2010. preferences found in it.
  2011.  
  2012. ReadPrefs
  2013.  
  2014. virtual void ReadPrefs (void);
  2015.  
  2016. Call inherited::ReadPrefs if you override this method
  2017.  
  2018. The purpose of this method is to read in settings from the dragon╒s
  2019. preferences file (from the resources specified in its ╘PrRo╒ 128 resource ╤
  2020. see description below) and change the appropriate instance variables
  2021. accordingly.  It should call preferences->GetPrefResource for each
  2022. preferences resource.  The Dragon::ReadPrefs method sets the following
  2023. instance variables:
  2024.  
  2025.     filesOnly            sleepValue[0..3]    resolveAliases    sleepTime
  2026.     followAliasChain    dirDepthLimit        autoQuit
  2027.  
  2028. You should check to see if preferences->GetPrefResource returns NULL when
  2029. overriding this method, and in any other method that might rely on a
  2030. preferences resource being in memory ╤ an incomplete preferences file should
  2031. never cause a crash.  See the code in the How do I╔ section above for an
  2032. example.
  2033.  
  2034. Note:    Remember that your dragon╒s preferences will come from the application
  2035. file if no preferences file could be found or created.
  2036.  
  2037. ResumeAEvent
  2038.  
  2039. virtual void ResumeAEvent (void);
  2040.  
  2041. Do not override
  2042.  
  2043. This method is called by Run whenever WaitNextEvent doesn╒t report an event
  2044. and one or more previously received Apple events are pending.  ResumeAEvent
  2045. asks the aeQueue object for the oldest pending Apple event, then calls
  2046. AEResumeTheCurrentEvent to handle the event normally.
  2047.  
  2048. Run
  2049.  
  2050. virtual void Run (void);
  2051.  
  2052. Do not override
  2053.  
  2054. Run contains the main event loop, which calls either DoEvent, DoIdle, or (if
  2055. there are any pending Apple events) ResumeAEvent.  The loop terminates only
  2056. when this->running is set to FALSE (by StopRunning).
  2057.  
  2058. SaveDocInfo
  2059.  
  2060. virtual void SaveDocInfo (Boolean refreshFinder);
  2061.  
  2062. Call SaveDocInfo right after you change one or more of the following values:
  2063.  
  2064. curFileType    curFileCreator    curFileFlags
  2065.  
  2066. curDocCreated    curDocModified
  2067.  
  2068. or any other field in *curDocPB that PBSetCatInfo takes as input.
  2069.  
  2070. Note:    To rename the current document, you should call FSpRename (rather than
  2071. just changing *curDocName) after calling SaveDocInfo (TRUE).
  2072.  
  2073. Warning:    If your dragon makes any low-level File Manager calls that leave
  2074. garbage in any fields in *curDocPB that PBSetCatInfo takes as input, then it
  2075. should do so after calling this method, or save and restore those values, or
  2076. refrain from calling SaveDocInfo at all.  Table 2 contains a partial list of
  2077. low-level File Manager calls that leave garbage in fields that PBSetCatInfo
  2078. uses.
  2079.  
  2080.     <Table 2 omitted>
  2081.  
  2082. SetUpMenus
  2083.  
  2084. virtual void SetUpMenus (void);
  2085.  
  2086. If you override this method, call inherited::SetUpMenus at the beginning of
  2087. your method and DrawMenuBar at the end
  2088.  
  2089. SetUpMenus is called by Start (unless autoQuit != FALSE).  It initializes
  2090. your dragon╒s menus, including (by default) a standard Apple Menu, a File
  2091. menu with just one item (Quit), and an Edit menu with the five basic editing
  2092. commands (Undo, Cut, Copy, Paste, and Clear).
  2093.  
  2094. ShowProgress
  2095.  
  2096. virtual void ShowProgress (void);
  2097.  
  2098. For future compatibility, you should call inherited::DoBusy if you override
  2099. this method
  2100.  
  2101. Override ShowProgress if you want your dragon to give the user some visual
  2102. indication of the progress it╒s making on processing the documents the user
  2103. drag-and-dropped on it.  If your dragon doesn╒t look inside directories
  2104. (i.e., if dirDepthLimit == 0) then you might want to show a progress bar
  2105. similar to the one the Finder puts up while copying files.  If it does look
  2106. in directories, then you could display the name of each document as it╒s
  2107. processed.
  2108.  
  2109. Warning:    ShowProgress is called for every file, folder, or disk
  2110. drag-and-dropped on your dragon (or sent in an Open Documents event from a
  2111. source other than the Finder) ╤ even ones that your dragon can╒t (for
  2112. whatever reason) process.  Keep this mind if you want to display the names
  2113. only of documents as they╒re processed ╤ you╒ll need to override
  2114. ProcessFile, ProcessDirectory, or ProcessDocsInDirectory (or some
  2115. combination of those three) instead.
  2116.  
  2117.     Also, your DoBusy method should not change *curDocFSS or *curDocPB in any
  2118. way.
  2119.  
  2120. Note:    Implementing a movable modal window (as an instance of a class that
  2121. you can override) is high on the list of future plans for Dragonsmith, but
  2122. adding it to Dragon will probably require significant changes to ProcessDoc
  2123. and ShowProgress.  If you override either of these methods, keep in mind
  2124. that your code may have to be changed later for compatibility with new
  2125. releases of Dragonsmith.
  2126.  
  2127. Start
  2128.  
  2129. virtual void Start (void);
  2130.  
  2131. Start initializes your dragon╒s run-time environment ╤ memory, menus,
  2132. preferences, events, etc.
  2133.  
  2134. StopProcessing
  2135.  
  2136. virtual void StopProcessing (OSErr err);
  2137.  
  2138. Call inherited::StopProcessing if you override this method
  2139.  
  2140. StopProcessing should be called whenever an error occurs that is serious
  2141. enough that processing should be stopped (including cancellation by the
  2142. user).  The parameter should specify the reason for stopping. 
  2143. Dragon::StopProcessing just sets abortProcessing = TRUE; your Dragon
  2144. subclass can display an error message or otherwise indicate that something
  2145. went wrong (but it should stop ╥quietly╙ if the user generated a cancel
  2146. event).
  2147.  
  2148. StopRunning
  2149.  
  2150. virtual void StopRunning (void);
  2151.  
  2152. This method sets running = FALSE, after calling StopProcessing if your
  2153. dragon is currently processing an Open Documents event.  The dragon╒s main
  2154. event loop will terminate as soon as control is returned to Run.
  2155.  
  2156. SuspendAEvent
  2157.  
  2158. virtual OSErr SuspendAEvent (AppleEvent *event, AppleEvent *reply,
  2159. AEHandlerFunc╩*handler, long refcon);
  2160.  
  2161. Do not override
  2162.  
  2163. SuspendAEvent is called by ProcessOdoc any time your dragon receives an Open
  2164. Documents event while processing a previously received one.  SuspendAEvent
  2165. asks the aeQueue object to add the event to its queue, then calls the
  2166. Toolbox routine AESuspendTheCurrentEvent to let the System know the event
  2167. isn╒t being handled.
  2168.  
  2169. Warning:    Be very careful if you decide to override this method.  Any
  2170. application that receives an Apple event while processing one received
  2171. earlier must either call AESuspendTheCurrentEvent or interrupt the first
  2172. event until handling of the second is completed.  It appears that dividing
  2173. CPU time between the handling of several Apple events (without calling
  2174. AESuspendTheCurrentEvent and AEResumeTheCurrentEvent at the appropriate
  2175. times) will cause the system to grow very confused!
  2176.  
  2177. WaitIdle
  2178.  
  2179. virtual Boolean WaitIdle (EventRecord *theEvent, long *sleep,
  2180. RgnHandle╩*mouseRgn);
  2181.  
  2182. WaitIdle will be called whenever your dragon gets an update, activate, null,
  2183. or OS event while it╒s waiting for AEInteractWithUser to return ╤ i.e.,
  2184. while it waits for the user to bring it to the foreground.  The default
  2185. behavior in the Dragon class is to let the main event handler, DoEvent, pass
  2186. the buck.  Please note that recursion is not a possibility unless you do
  2187. some very strange overriding of the DoActivate, DoUpdateEvent, DoOSEvent,
  2188. DoSuspend, or DoResume methods.
  2189.  
  2190.  
  2191. ------------------------------------------------------
  2192. RESOURCES
  2193. ------------------------------------------------------
  2194.  
  2195. This section briefly describes all of the resources that should be present
  2196. in your dragon╒s project resource file (with the exception of the ╘SIZE╒ and
  2197. signature resources, which THINK╩C will add to the built application).  All
  2198. of the project resource files provided with Dragonsmith╩1.1 contain these
  2199. resources.  The best way to gain a full understanding of the
  2200. Dragonsmith-specific resources is to view them in ResEdit and look for
  2201. mentions of them in the Dragonsmith source code.
  2202.  
  2203. Dragonsmith resources
  2204.  
  2205. The following resources have Dragonsmith-specific functions:
  2206.  
  2207. ALRT 129        Alert used by Dragon::Error.
  2208.  
  2209. DITL 129        Dialog item list for use with ╘ALRT╒ 129.
  2210.  
  2211. DrPr 128        Dragon class preferences.  The following Dragon instance variables
  2212. are all copied from values in this resource:
  2213.         autoQuit            resolveAliases    followAliasChain
  2214.         sleepValue[0..3]    filesOnly        dirDepthLim
  2215. If your dragon sets any of these instance variables in its constructor, then
  2216. you should put the same values into the fields in your project resource
  2217. file╒s ╘DrPr╒ 128 resource.  Forgetting to do so can cause tremendous
  2218. frustration.
  2219.  
  2220. GChk 128        A list of Gestalt calls and the values that they should return.  InitMilieu
  2221. passes this resource to the GestaltBatchCheck function, which returns noErr if the
  2222. run-time environment is sufficient for the dragon to function properly.  Each entry
  2223. in the list has the following structure:
  2224.     typedef struct {
  2225.         OSType  selector;      // Selector to call Gestalt with
  2226.         short   compOp;        // Type of comparison to make
  2227.         short   failureError;  // Error to return if check fails
  2228.         long    compValue;     // Check Gestalt result against this
  2229.     }
  2230. Possible values for the compOp field are listed in the file GestaltUtils.h.
  2231.  
  2232. MENU 128        Apple menu,
  2233.     129        File menu,
  2234.     130        Edit menu.
  2235.  
  2236. MoMa 128        Number of times to call MoreMasters.
  2237.  
  2238. PrRo 128        Preferences roster ╤ a list of the dragon╒s preferences resources. 
  2239. You must add to this list whenever you add a new preferences resource.
  2240.  
  2241. STR 128        Name of the dragon╒s preferences file.  To prevent a preferences
  2242. file from being created, put a null string in this resource and delete the
  2243. ╘FREF╒ resource for the type designated by the instance variable
  2244. prefsFileType.
  2245.  
  2246. ResEdit templates for the Dragonsmith-specific resources are available in
  2247. the ╘Dragonsmith TMPLs╒ file ╤ keep this file open whenever viewing or
  2248. editing them.
  2249.  
  2250. Finder-related resources
  2251.  
  2252. The following resoures are used by the Finder to correctly launch an
  2253. application, control drag-and-drop onto it, and display its icons and
  2254. information in the Finder:
  2255.  
  2256. <signature> 0    The type of this resource should be the same as your
  2257. application╒s signature (set via the ╘Set Project Type╔╒ dialog in THINK╩C).
  2258.  It contains a copyright string for the application.
  2259.  
  2260. BNDL 128        This resource coordinates an application╒s Finder-related
  2261. resources.  You can ResEdit 2.1╒s ╘BNDL╒ editor to modify this resource as
  2262. well as the ╘FREF╒, signature, and icon resources.
  2263.  
  2264. FREF 128, etc.    These resources designate the types of files your dragon can
  2265. process.  Make sure you have one for every document type your dragon is
  2266. capable of processing, plus one (╘APPL╒) for the application itself, plus
  2267. one for the file type designated by the instance variable prefsFileType
  2268. (normally ╘pref╒) if your dragon creates a preferences file.
  2269.  
  2270. Use the values ╘fold╒ and ╘disk╒ to allow drag-and-drop of folders and
  2271. volumes (respectively) onto your dragon.
  2272.  
  2273. Use the value ╘****╒ to specify that your dragon can process files (not
  2274. folders or volumes) of any type.
  2275.  
  2276. hfdr
  2277. styl
  2278. TEXT 128        These three resources in combination provide Ballon Help for your
  2279. dragon╒s icon in the Finder.  Delete all three if you don╒t want this
  2280. feature.
  2281.  
  2282. icl4,
  2283. icl8,
  2284. ICN#,
  2285. ics#,
  2286. ics4,
  2287. ics8            Icons for your dragon╒s application and files.
  2288.  
  2289. SIZE ╨1        The SIZE resource must be set up correctly for an application to
  2290. accept Apple events, and the Dragon class relies on Apple events ╤ if a
  2291. dragon can╒t get an Open Documents event, it won╒t do anything.  Don╒t put
  2292. your own ╘SIZE╒ resource in the .rsrc file ╤ use the SIZE settings available
  2293. by choosing ╘Set Project Type╔╒ from THINK╩C╒s Project menu.
  2294.  
  2295. vers 1        This is the ╘true╒ version string which appears in the Get Info╔
  2296. window
  2297.  
  2298. vers 2        This string appears directly under your application╒s name in its Get
  2299. Info╔ window in the Finder.  The dragons provided with Dragonsmith use the
  2300. words ╘a Dragon sub-species╒ in this string, but you╒re not required to
  2301. follow this convention in your own dragons.
  2302.  
  2303. Inside Macintosh, Volume VI has an extensive description of Finder-related
  2304. resources on pages 9-5 to 9-24 and 9-34 to 9-35 ╤ read it for more
  2305. information on these resources.  Keep in mind that many of these resources
  2306. must be modified before your dragon╒s first built version, or you may have
  2307. to rebuild the desktop to make the Finder╒s behavior reflect any changes in
  2308. them.
  2309.  
  2310.  
  2311.